Know how RESTful your API is: An Overview of the Richardson Maturity Model

Most of the time, I see developers are bit confused about the term REST. For some enterprise application developers, the meaning of REST is JSON i.e. if they are using JSON in their application, which means they working on REST API, which is not true to some extent. Let's take a look what exactly a REST API is.

Let's say we designed a REST API. How do we know how much Restful API is? Some developers call it "Not Restful API", some call it "Partially Restful API", for some, it is "Fully Restful API", and for some "It is not REST API at all or they call it SOAP based web service". Imagine it as a spectrum from Not Restful to Fully Restful API. To know at which level API stand, Richardson introduces a model called Richardson Maturity Model. As the name itself suggests, it tells about the maturity level of REST API.

According to the Richardson Maturity Model, any REST API belongs to any of the maturity levels from Level 0 to Level 3, mentioned below.

It's not necessary that every REST API developed should be as high as Level 3. But this model helps the developers of REST API to know at which Level their API belongs to and how can they make their API better by moving up in the above model hierarchy.

Level 0: The Swamp of POX

1. API designed at this level are not at all Rest APIs and This is where SOAP based web services takes place.
2. At this Level,There is no concept of Resource Based URI, Hypermedia, and no proper use of HTTP Protocol (which are key characteristics of a REST API). In fact, the API, which belongs to this Level, does not make use or leverages the full potential of the HTTP protocol. HTTP is merely treated as a Transport Layer protocol or just a Tunneling Mechanism between Client and Server.

Example: Let's look at a twitter API that allows the users to create a tweet, comment on a tweet, follow the user, share the tweets, etc. A sample URI or End Point for such twitter API designed at Level 0 can be http://<hostname>:<port>/twitter.

Here's how the Endpoint at the server side will know what to do with an incoming request from the Client or what operations to perform like create a tweet, delete a tweet, or comment on a tweet etc. Also, how can an API Client tell the Service Endpoint to do different operations?

In SOAP-Based web services, this is done by sending a message or request body, which is sent to the endpoint via SOAP protocol. The Request Body essentially contains all information about the operation (like DELETE tweet, CREATE tweet, Update tweet etc.) and data on which the operation is performed, e.g. for creating a tweet , the Request body may be something like:

Similarly for deleting a tweet, Request Body may <delete-tweet>...</delete-tweet>. If there is some error in creating a tweet, probably we will have a response like <create-tweet-error>Error cause</create-tweet-error> from the server.

Notice that all these requests go to a single endpoint and that's how the endpoint knows how to do different operations. Since Request body itself identifies what kind of operation needs to be performed, it makes sense to use single URI for all operations. Or we can say that the same http method can be used for each operation on tweet because all the details about the operation are carried in the Request Body (called SOAP XML also) and we are not leveraging the potential of HTTP Methods/Verbs. As HTTP is used just as a tunnel between the client and server at this Level.

This is called swamp of POX (plain old XML) approach. So, everything is defined by XML in the case of SOAP web service and that is called POX(Plain Old XML).

LEVEL 1: Resource BASED ADDRESS/URI

1. This is a starting Level for a REST API. In this Level, the Concept of Resource-based Address is introduced, which tells you there should be Individual URI for each Resource on the server (unlike LEVEL 0 where we have a single URI for each incoming request from Client).
2. It's like reducing the burden from the single endpoint (LEVEL 0 end Point which handles all operations) into multiple Resource Based URIs like Divide and Conquer algorithm.
   Example: Create tweet request going to URI1, delete tweet Request is going to URI2 etc. So whether we create a new tweet, delete the tweet, or we update the tweet, the operation information (create, update, delete of tweet) is still in the Request body. In the above twitter API, we can think TWEET, COMMENT, and FOLLOWER as different resources in above application.
3. If we just designed Resource-based URI and nothing else, then we are at LEVEL 1 of the maturity model. In this, the HTTP is just used as a tunnel between client and server and we have not leveraged the potential of HTTP as an application Layer Protocol.
4. Most of the developers who are beginners for REST design REST API at this LEVEL.
5.  

LEVEL 2: Utilize Potential of HTTP as Application Layer Protocol

1. REST developed under this level leverages the full potential of HTTP as an application Layer Protocol.
2. REST API developed at this LEVEL uses Standard HTTP methods/verbs and different HTTP status codes to do different operations on Resource URI. So, the Request Body will no longer carry Operation information at this level. Hence, this API is much more mature than the API developed at LEVEL 0 and LEVEL 1.

Example: Let's say we want to create a tweet and decide later we want to delete it. So we will have Resource "Tweet" and we can form resource based URI like http://<host name>:<port>/api/tweets. Now, how to tell this single resource based URI to do different operations and the answer is using HTTP verbs like below.

A sample Post request for creating a tweet is as below

A sample Delete Request for deleting a tweet at server side.

In this example, we observe both requests are going to single Resource Based Address and Operations is not managed by Request Body anymore and we make use of HTTP methods to perform different operations on the same URI and Request Body merely carrying raw data on which the operation will be performed at the server side.We are making use of proper status codes also so that it can be helpful for a client that whether the operation is successful or not.

LEVEL 3: Use Hypermedia or HATEOAS

1. In LEVEL 1, the Resource-Based URI concept is introduced and in LEVEL 2, we leveraged the full potential of HTTP protocol using HTTP methods. LEVEL 3 makes use of Hypermedia (also Called HATEOAS--Hypermedia as Engine of Application state in REST world), which drives the interaction for the API Client. Generally, the API Client is not aware of all resource endpoints and REST does not deal much with API documents (which can tell API client information about all endpoints), unlike SOAP where we have WSDL, which provides information about service to the API Client.
2. Different Resource Based Endpoints are made aware to API Client using concept HATEOAS i.e. sending some hypermedia as the response of endpoint response which in turns acts as Engine of Application state and hence the name HATEOAS. The HATEOAS concept in REST API makes API self-documented and hence no need for API documentation.
3. API developed at this LEVEL 3 is generally considered as fully RESTful API and this is where we see the charm of REST API.

Example: Let's say the API Client wants to get all the tweets available in the Server and the list of comments on a particular tweet. To get this information, the Client should be aware of both the endpoints and URI performing their tasks respectively.

If we observe the above example carefully, once the client makes an HTTP GET request to /tweets endpoint, the Client gets all the tweets in the server along with some extra information, which conveys to the Client. In that case, it wants to get all comments on a tweet, use the endpoint sent in response, which is nothing but the concept of Hypermedia in Rest world. So now the Client does not need to know the endpoint to get all comments on a tweet, in fact, the API itself is telling the client to use the endpoint, which is sent in response. So Hypermedia in response is driving the application state and that's why the name HATEOAS(Hypermedia as Engine of Application State).

Conclusion: 

1. This model simplifies the process of developing REST API and help developers how can they design a mature Restful API. REST is a term first coined by Roy Fielding. Most of the concept of REST is inspired by HTTP protocol specification whose author is also Roy Fielding and hence there should not be much surprise that REST leverages the full potential of HTTP Specifications. Using HTTP Protocol just a data transport media(i.e Transport layer) between client and server is not recommended while designing REST API. Since HTTP lets you customize the behavior of server-side application using its specifications(like HTTP methods, HTTP status codes, Content-type etc.), one should make complete use of it and that's where we see actual benefit of HTTP as application layer protocol in REST API.
2. Also, one important aspect to notice here is that making use of JSON media type, as HTTP exchange between client and server does not guarantee that you are dealing with REST API. JSON is merely most preferred MEDIA TYPE in REST World because JSON is considered to be less verbose from other MEDIA TYPES like XML, XHTML, PLAINTEXT etc. and JSON objects are easily understood by any web client (e.g. In case we are dealing with an application, which displays REST API data in form of UI, then JSON  media type can be the best choice in that application because browser/web-client can easily understand JSON objects).
3. In short, A Restful API implementation at server side must be like below:
   REST = RESOURCE BASED URI+ Full Utilization of HTTP Specification+Hypermedia (or   HATEOAS)
4. The most preferred API for developing Rest API is JAX-RS( As part of JEE specification) and Spring BOOT (An open source third Party Framework).
5. Note that before going through this article, sound knowledge of HTTP and REST Architecture is necessary.

To learn about Red Hat Openshift Container Platform, allowing you to provision, manage, and scale container-based applications.